home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3p / uspsema.z / uspsema
Encoding:
Text File  |  1998-10-20  |  7.8 KB  |  133 lines
  1.  
  2.  
  3.  
  4. UUUUSSSSPPPPSSSSEEEEMMMMAAAA((((3333PPPP))))                                                        UUUUSSSSPPPPSSSSEEEEMMMMAAAA((((3333PPPP))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      uspsema - acquire a semaphore
  10.  
  11. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<uuuulllloooocccckkkkssss....hhhh>>>>
  13.  
  14.      iiiinnnntttt uuuussssppppsssseeeemmmmaaaa ((((uuuusssseeeemmmmaaaa____tttt ****sssseeeemmmmaaaa))));;;;
  15.  
  16. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  17.      _u_s_p_s_e_m_a decrements the count of the previously allocated semaphore
  18.      specified by _s_e_m_a. If the count is then negative, the semaphore will
  19.      logically block the calling process until the count is incremented due to
  20.      a _u_s_v_s_e_m_a(3P) call made by another process.  The count can be interpreted
  21.      in the following way: if it is greater than zero, there are 'count'
  22.      resources available, namely 'count' processes can call _u_s_p_s_e_m_a and not
  23.      block; if the count is negative then the absolute value of count is the
  24.      number of waiting processes.  _u_s_t_e_s_t_s_e_m_a(3P) can be used to obtain the
  25.      semaphore count.  _u_s_p_s_e_m_a can operate on either polling (those allocated
  26.      via _u_s_n_e_w_p_o_l_l_s_e_m_a(3P)) or non-polling (those allocated via _u_s_n_e_w_s_e_m_a(3P))
  27.      semaphores.  The semantics of _u_s_p_s_e_m_a are different for the two types of
  28.      semaphores.
  29.  
  30.      For non-polling semaphores, the caller is actually suspended if the
  31.      semaphore is not available.  During suspension signals may be received
  32.      and processed.  The caller must not _l_o_n_g_j_m_p out of a signal handler and
  33.      bypass the semaphore operation as this will result in corruption of the
  34.      internal data structures of the semaphore.  It the user does this, the
  35.      semaphore must be re-initialized via _u_s_i_n_i_t_s_e_m_a(3P).  _u_s_p_s_e_m_a uses the
  36.      _u_s_e_m_a(7M) device to perform the actual suspending of the caller if
  37.      necessary.  Processes are unblocked in FIFO order.  If the current owner
  38.      of the semaphore abnormally exits while still holding one or more
  39.      semaphores, no corrective action is taken.  This means that the only way
  40.      a process that is blocked waiting for a semaphore to recover is to take a
  41.      signal, longjmp out of the handler and re-initialize the semaphore (see
  42.      _F_U_T_U_R_E _D_I_R_E_C_T_I_O_N_S).
  43.  
  44.      With either type of semaphore, the semaphore can be made recursive by
  45.      using the CCCCSSSS____RRRREEEECCCCUUUURRRRSSSSIIIIVVVVEEEEOOOONNNN option to _u_s_c_t_l_s_e_m_a(3P).  Recursive semaphores
  46.      permit the current owner to acquire the semaphore multiple times.  A
  47.      matching number of _u_s_v_s_e_m_a(3P) calls will release the semaphore.
  48.      Recursive semaphores only work with semaphores that have been initialized
  49.      to 1 (i.e. mutual exclusion semaphores).
  50.  
  51.      For polling semaphores, the caller is never actually suspended - either 1
  52.      or 0 is returned based on whether the semaphore was available.  If the
  53.      semaphore was not available, the process is placed on the queue of
  54.      processes waiting for the semaphore and the caller must perform either a
  55.      _p_o_l_l(2) or _s_e_l_e_c_t(2) on the file descriptor returned by
  56.      _u_s_o_p_e_n_p_o_l_l_s_e_m_a(3P) to determine when the semaphore becomes available.
  57.      The PPPPOOOOLLLLLLLLIIIINNNN event should be used with _p_o_l_l(2).  The semaphore file
  58.      descriptor should be passed in as a read descriptor for _s_e_l_e_c_t(2).  The
  59.      caller must not call _u_s_p_s_e_m_a again until having acquired the semaphore by
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. UUUUSSSSPPPPSSSSEEEEMMMMAAAA((((3333PPPP))))                                                        UUUUSSSSPPPPSSSSEEEEMMMMAAAA((((3333PPPP))))
  71.  
  72.  
  73.  
  74.      receiving a ready status from _s_e_l_e_c_t or _p_o_l_l.  Use _u_s_c_p_s_e_m_a(3P) to
  75.      acquire a semaphore if its available but not be queued if it isn't.
  76.  
  77.      Note that only in the transition from unavailable to available will the
  78.      file descriptor of a pollable semaphore trip a _p_o_l_l(2) or _s_e_l_e_c_t(2) call.
  79.      In other words, _p_o_l_l(2) or _s_e_l_e_c_t(2) will block if you have already
  80.      successfully acquired the semaphore with _u_s_p_s_e_m_a.
  81.  
  82.      In order to use a semaphore, the caller must have joined the shared arena
  83.      out of which the semaphore is allocated (via _u_s_i_n_i_t(3P)), and have a file
  84.      descriptor to a _u_s_e_m_a device to suspend on.  As a convenience, _u_s_p_s_e_m_a
  85.      will automatically do this for members of a share group, or for related
  86.      (via _f_o_r_k(2)) processes.  This automatic facility can generate the same
  87.      errors as _u_s_i_n_i_t(3P), and _u_s_o_p_e_n_p_o_l_l_s_e_m_a(3P).  These errors will be
  88.      passed back to the caller.  If tracing is enabled (see _u_s_i_n_i_t(_3_P)) then
  89.      any errors will cause a message to be printed to _s_t_d_e_r_r.  To avoid these
  90.      errors and therefore not need to check for errors on every _u_s_p_s_e_m_a call,
  91.      have each process call _u_s_i_n_i_t(_3_P) and each user of a pollable semaphore
  92.      call _u_s_o_p_e_n_p_o_l_l_s_e_m_a(3P).
  93.  
  94.      The following errors can occur due to misuse of a semaphore:
  95.  
  96.      [EBADF]        The underlying file descriptor for the semaphore was
  97.                     closed or re-used by the application.
  98.  
  99.      [EBADF]        _u_s_p_s_e_m_a was called on a polling semaphore which was not
  100.                     available and no one had ever done a _u_s_o_p_e_n_p_o_l_l_s_e_m_a(3P)).
  101.  
  102.      [ERANGE]       The semaphore queue overflowed.  This is caused when using
  103.                     a polling semaphore and the caller has 'double-tripped',
  104.                     i.e. calls _u_s_p_s_e_m_a more than once without properly having
  105.                     received the semaphore via _p_o_l_l(2) or _s_e_l_e_c_t(2).  This can
  106.                     also occur if the number of users of a semaphore exceeds
  107.                     the number that the arena was originally configured for.
  108.                     This will never happen if ALL users register with the
  109.                     arena via _u_s_i_n_i_t(3P).
  110.  
  111. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  112.      uscpsema(3P), usctlsema(3P), usinit(3P), usinitsema(3P), usnewsema(3P),
  113.      usnewpollsema(3P), usopenpollsema(3P), ustestsema(3P), usvsema(3P),
  114.      usema(7M).
  115.  
  116. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  117.      Upon successful completion the semaphore has been acquired and a value of
  118.      1 is returned.  For polling semaphores, 0 is returned if the semaphore is
  119.      unavailable.  On error, -1 is returned and _e_r_r_n_o is set to indicate the
  120.      error.
  121.  
  122. FFFFUUUUTTTTUUUURRRREEEE DDDDIIIIRRRREEEECCCCTTTTIIIIOOOONNNNSSSS
  123.      To facilitate error handling, _u_s_p_s_e_m_a will return distinctive affirmative
  124.      results based on whether the semaphore was acquired normally or was
  125.      acquired due to the owner having abnormally terminated.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.